Skip to content

chore(release): verify SHA512 against actual archive (#687)#688

Merged
kcenon merged 1 commit intodevelopfrom
chore/issue-687-verify-sha512-against-actual-archive
May 3, 2026
Merged

chore(release): verify SHA512 against actual archive (#687)#688
kcenon merged 1 commit intodevelopfrom
chore/issue-687-verify-sha512-against-actual-archive

Conversation

@kcenon
Copy link
Copy Markdown
Owner

@kcenon kcenon commented May 3, 2026

Closes #687

Part of kcenon/common_system#674.

What

Adds an independent SHA512 verification step to .github/workflows/on-release-sync-registry.yml. The new verify-archive job re-downloads the GitHub release archive from https://github.com/kcenon/monitoring_system/archive/refs/tags/<tag>.tar.gz, recomputes its SHA512, and runs before the existing sync job that calls the reusable workflow at kcenon/common_system/.github/workflows/sync-vcpkg-registry.yml@main.

Why

Detected via microsoft/vcpkg#51511 and kcenon/vcpkg-registry#87 - every kcenon port shipped a mismatched SHA512 because release workflows never compared the computed value against the actual archive. Cold-cache vcpkg consumers (new CI runners, fresh users) hit 100% install failure when the SHA in vcpkg-registry/ports/kcenon-monitoring-system/portfile.cmake does not match the bytes the consumer actually fetches.

The reusable sync workflow at kcenon/common_system was already hardened in kcenon/common_system PR #676, so monitoring_system inherits that check via the uses: reference. Adding a caller-side verification job in this repo provides defense-in-depth: if the reusable workflow is ever repointed, refactored, or its check is removed, this repo's release pipeline still fails fast on a bad archive.

Where

File Change
.github/workflows/on-release-sync-registry.yml New verify-archive job added before sync; sync now declares needs: verify-archive

Audit summary (other workflows considered)

Workflow Touches portfile SHA? Action
on-release-sync-registry.yml Calls reusable sync (which writes SHA512) Hardened (this PR)
ci.yml No (build/test only) No change
sanitizers.yml No (build/test only) No change
benchmarks.yml No (perf measurement) No change
coverage.yml No (coverage upload) No change
cve-scan.yml, dependency-security-scan.yml, osv-scanner.yml, sbom.yml Hash dependencies, not portfile SHA Out of scope
static-analysis.yml, integration-tests.yml, doc-audit.yml, build-Doxygen.yaml No SHA writes No change
validate-vcpkg-chain.yml Validates vcpkg consumer build, does not write portfile SHA No change

Only on-release-sync-registry.yml participates in writing SHA512 to portfiles, so a single inline verification job in that workflow is appropriate. No composite action extraction is needed.

How

The new verify-archive job runs on ubuntu-latest and:

  1. Downloads the release archive to a temp file via curl -fsSL --retry 3 --retry-delay 2 -o <file> <url> (file-based, never piped into sha512sum).
  2. Verifies the downloaded file is at least 1024 bytes.
  3. Computes sha512sum of the file.
  4. Refuses to proceed if the digest equals the well-known empty-input SHA512 (cf83e1357eefb8bdf...), which would indicate a silent fetch failure.
  5. The sync job declares needs: verify-archive, so a failed verification short-circuits the registry update before any portfile commit.

The reusable sync workflow at kcenon/common_system performs the same comparison server-side using the SHA it just wrote to the portfile, providing two-layer protection.

Test Plan

How a reviewer can validate the new job fires

  1. After merge, cut a release tag (v0.x.y). The Sync Registry on Release workflow triggers automatically.
  2. Inspect the run log for the new Verify release archive SHA512 job. On a healthy release, it prints:
    Fetching https://github.com/kcenon/monitoring_system/archive/refs/tags/v0.x.y.tar.gz for SHA512 verification...
    SHA512 of https://github.com/kcenon/monitoring_system/archive/refs/tags/v0.x.y.tar.gz:
      <128-char hex digest>
    Archive size: <N> bytes
    
  3. The sync job then runs only if verify-archive succeeded.

Negative-path verification

To confirm the guard fires on a bad archive URL, a maintainer can temporarily replace the TAG env value in the workflow with a non-existent tag on a feature branch and trigger the workflow against a synthetic release - the verify-archive job will fail with ::error::Failed to download release archive, and the sync job will be skipped.

Acceptance Criteria

  • Audit identifies all release workflow files in this repo that compute or commit SHA512 (on-release-sync-registry.yml only)
  • That workflow includes a "verify SHA against actual archive" gate that runs before the registry sync commits the portfile
  • File-based hashing is used (no curl | sha512sum) so 404s cannot produce the empty-input sentinel hash
  • Audit summary documents why the other 14 workflows do not need changes

References

Add an independent SHA512 verification step to the release sync
workflow that re-downloads the GitHub release archive and recomputes
the digest before the reusable sync workflow commits a new portfile
to the vcpkg overlay registry.

The reusable sync workflow at kcenon/common_system already performs
this check internally (see kcenon/common_system#675, PR #676), but
adding a caller-side verify-archive job in this repo guards against
drift if the reusable workflow changes or is repointed in the future.

Implementation notes:
- File-based hashing (curl -o file, then sha512sum) instead of piping
  curl into sha512sum, so a 404 cannot silently produce the empty-input
  hash cf83e1357eefb8bdf...
- Explicit empty-input SHA512 sentinel guard
- Archive size sanity check (>= 1024 bytes)
- sync job depends on verify-archive via needs:, so a failed
  verification halts the registry update before any commit

Audit summary:
- on-release-sync-registry.yml: hardened (this PR)
- All other workflows in this repo (ci.yml, sanitizers.yml,
  benchmarks.yml, etc.): do not compute or write SHA512 to portfiles,
  no change needed.

Closes #687
Part of kcenon/common_system#674
@kcenon kcenon merged commit 7c86947 into develop May 3, 2026
6 checks passed
@kcenon kcenon deleted the chore/issue-687-verify-sha512-against-actual-archive branch May 3, 2026 13:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant